Skunkware 5/Skunkware 5.iso/man/cat.n/format.n

Text File | 1995-07-25 | 13KB | 265 lines

     ffffoooorrrrmmmmaaaatttt((((nnnn))))                    TTTTccccllll (((( ))))                    ffffoooorrrrmmmmaaaatttt((((nnnn))))



     _________________________________________________________________

     NNNNAAAAMMMMEEEE
          format - Format a string in the style of sprintf

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          ffffoooorrrrmmmmaaaatttt _f_o_r_m_a_t_S_t_r_i_n_g ?_a_r_g _a_r_g ...?
     _________________________________________________________________


     IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNNN
          This command generates a formatted string in the same way as
          the  ANSI  C  sssspppprrrriiiinnnnttttffff  procedure  (it  uses  sssspppprrrriiiinnnnttttffff  in its
          implementation).  _F_o_r_m_a_t_S_t_r_i_n_g indicates how to  format  the
          result, using %%%% conversion specifiers as in sssspppprrrriiiinnnnttttffff, and the
          additional  arguments,  if  any,  provide   values   to   be
          substituted  into  the result.  The return value from ffffoooorrrrmmmmaaaatttt
          is the formatted string.


     DDDDEEEETTTTAAAAIIIILLLLSSSS OOOONNNN FFFFOOOORRRRMMMMAAAATTTTTTTTIIIINNNNGGGG
          The command operates by scanning _f_o_r_m_a_t_S_t_r_i_n_g from  left  to
          right.  Each character from the format string is appended to
          the result string unless it  is  a  percent  sign.   If  the
          character is a %%%% then it is not copied to the result string.
          Instead,  the  characters  following  the  %%%%  character  are
          treated as a conversion specifier.  The conversion specifier
          controls the conversion of the  next  successive  _a_r_g  to  a
          particular  format  and the result is appended to the result
          string in place of the conversion specifier.  If  there  are
          multiple  conversion  specifiers  in the format string, then
          each one controls the conversion of one additional _a_r_g.  The
          ffffoooorrrrmmmmaaaatttt  command  must be given enough _a_r_gs to meet the needs
          of all of the conversion specifiers in _f_o_r_m_a_t_S_t_r_i_n_g.

          Each conversion specifier may contain up  to  six  different
          parts: an XPG3 position specifier, a set of flags, a minimum  |
          field  width,  a  precision,  a  length  modifier,   and   a
          conversion  character.   Any  of these fields may be omitted
          except for the conversion character.  The  fields  that  are
          present   must   appear  in  the  order  given  above.   The
          paragraphs below discuss each of these fields in turn.

          If the %%%% is followed by a decimal number  and  a  $$$$,  as  in  |
          ``%%%%2222$$$$dddd'',  then  the  value to convert is not taken from the  |
          next sequential argument.  Instead, it  is  taken  from  the  |
          argument indicated by the number, where 1 corresponds to the  |
          first _a_r_g.  If the conversion  specifier  requires  multiple  |
          arguments  because  of  ****  characters  in the specifier then  |
          successive arguments are used, starting  with  the  argument  |
          given  by the number.  This follows the XPG3 conventions for  |
          positional  specifiers.   If  there   are   any   positional  |



     Page 1                                          (printed 7/17/95)






     ffffoooorrrrmmmmaaaatttt((((nnnn))))                    TTTTccccllll (((( ))))                    ffffoooorrrrmmmmaaaatttt((((nnnn))))



          specifiers  in  _f_o_r_m_a_t_S_t_r_i_n_g then all of the specifiers must  |
          be positional.

          The second portion of a conversion specifier may contain any
          of the following flag characters, in any order:

          ----         Specifies that the converted  argument  should  be
                    left-justified  in its field (numbers are normally
                    right-justified with leading spaces if needed).

          ++++         Specifies that a number should always  be  printed
                    with a sign, even if positive.

          _s_p_a_c_e     Specifies that a space  should  be  added  to  the
                    beginning  of  the  number  if the first character
                    isn't a sign.

          0000         Specifies that the number should be padded on  the
                    left with zeroes instead of spaces.

          ####         Requests an alternate output form.  For  oooo  and  OOOO
                    conversions  it guarantees that the first digit is
                    always 0000.  For  xxxx  or  XXXX  conversions,  0000xxxx  or  0000XXXX
                    (respectively)  will  be added to the beginning of
                    the result unless it is zero.  For  all  floating-
                    point   conversions   (eeee,  EEEE,  ffff,  gggg,  and  GGGG)  it
                    guarantees that the result always  has  a  decimal
                    point.   For gggg and GGGG conversions it specifies that
                    trailing zeroes should not be removed.

          The third portion of a  conversion  specifier  is  a  number
          giving  a  minimum  field  width for this conversion.  It is
          typically used to make columns line up in tabular printouts.
          If the converted argument contains fewer characters than the
          minimum field width then it will be padded so that it is  as
          wide as the minimum field width.  Padding normally occurs by
          adding extra spaces on the left of the  converted  argument,
          but  the  0000  and ---- flags may be used to specify padding with
          zeroes  on  the  left  or  with   spaces   on   the   right,
          respectively.   If the minimum field width is specified as ****
          rather than a number, then the next argument to  the  ffffoooorrrrmmmmaaaatttt
          command  determines  the  minimum  field width; it must be a
          numeric string.

          The fourth portion of a conversion specifier is a precision,
          which consists of a period followed by a number.  The number
          is used in different ways for different conversions.  For eeee,
          EEEE,  and  ffff  conversions it specifies the number of digits to
          appear to the right of the  decimal  point.   For  gggg  and  GGGG
          conversions  it  specifies  the  total  number  of digits to
          appear, including those on both sides of the  decimal  point
          (however, trailing zeroes after the decimal point will still



     Page 2                                          (printed 7/17/95)






     ffffoooorrrrmmmmaaaatttt((((nnnn))))                    TTTTccccllll (((( ))))                    ffffoooorrrrmmmmaaaatttt((((nnnn))))



          be omitted unless the  ####  flag  has  been  specified).   For
          integer conversions, it specifies a mimimum number of digits
          to print (leading zeroes will be added if necessary).  For ssss
          conversions it specifies the maximum number of characters to
          be printed; if the string  is  longer  than  this  then  the
          trailing  characters  will  be dropped.  If the precision is
          specified with **** rather than a number then the next argument
          to the ffffoooorrrrmmmmaaaatttt command determines the precision; it must be a
          numeric string.

          The fourth part  of  a  conversion  specifier  is  a  length
          modifier,  which  must  be  hhhh or llll.  If it is hhhh it specifies
          that the numeric value should be truncated to a 16-bit value
          before  converting.   This  option  is rarely useful.  The llll
          modifier is ignored.

          The last thing in a conversion specifier  is  an  alphabetic
          character   that  determines  what  kind  of  conversion  to
          perform.  The following conversion characters are  currently
          supported:

          dddd         Convert integer to signed decimal string.

          uuuu         Convert integer to unsigned decimal string.

          iiii         Convert integer to  signed  decimal  string;   the
                    integer may either be in decimal, in octal (with a
                    leading 0000) or in hexadecimal (with a leading 0000xxxx).

          oooo         Convert integer to unsigned octal string.

          xxxx or XXXX    Convert integer to  unsigned  hexadecimal  string,
                    using   digits   ``0123456789abcdef''  for  xxxx  and
                    ``0123456789ABCDEF'' for XXXX).

          cccc         Convert  integer  to  the   8-bit   character   it
                    represents.

          ssss         No conversion; just insert string.

          ffff         Convert floating-point number  to  signed  decimal
                    string of the form _x_x._y_y_y, where the number of _y's
                    is determined by the precision (default:  6).   If
                    the  precision  is  0  then  no  decimal  point is
                    output.

          eeee or eeee    Convert  floating-point   number   to   scientific
                    notation  in  the form _x._y_y_yeeee++++_____z_z, where the number
                    of _y's is determined by  the  precision  (default:
                    6).   If  the precision is 0 then no decimal point
                    is output.  If the  EEEE  form  is  used  then  EEEE  is
                    printed instead of eeee.



     Page 3                                          (printed 7/17/95)






     ffffoooorrrrmmmmaaaatttt((((nnnn))))                    TTTTccccllll (((( ))))                    ffffoooorrrrmmmmaaaatttt((((nnnn))))



          gggg or GGGG    If the exponent is less than -4 or greater than or
                    equal  to  the  precision,  then convert floating-
                    point number as for %%%%eeee or %%%%EEEE.   Otherwise  convert
                    as for %%%%ffff.  Trailing zeroes and a trailing decimal
                    point are omitted.

          %%%%         No conversion: just insert %%%%.

          For the numerical conversions the argument  being  converted
          must be an integer or floating-point string; format converts
          the argument to binary and then converts it back to a string
          according to the conversion specifier.


     DDDDIIIIFFFFFFFFEEEERRRREEEENNNNCCCCEEEESSSS FFFFRRRROOOOMMMM AAAANNNNSSSSIIII SSSSPPPPRRRRIIIINNNNTTTTFFFF
          The behavior of the format command is the same as the ANSI C  |
          sssspppprrrriiiinnnnttttffff procedure except for the following differences:       |

          [1]                                                                ||
               %%%%pppp and %%%%nnnn specifiers are not currently supported.

          [2]  For %%%%cccc conversions  the  argument  must  be  a  decimal
               string,   which   will   then   be   converted  to  the
               corresponding character value.

          [3]  The llll modifier is ignored;  integer values  are  always  |
               converted as if there were no modifier present and real  |
               values are always converted as if the llll  modifier  were  |
               present  (i.e.  type  ddddoooouuuubbbblllleeee  is  used for the internal  |
               representation).  If the hhhh modifier is  specified  then  |
               integer   values   are   truncated   to   sssshhhhoooorrrrtttt  before  |
               conversion.


     KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
          conversion specifier, format, sprintf, string, substitution



















     Page 4                                          (printed 7/17/95)